//===================================================================
// 项目名 : Hbt.Cur
// 文件名 : IHbtSingleUserLoginService.cs
// 创建者 : Lean365
// 创建时间: 2024-01-22 17:30
// 版本号 : V0.0.1
// 描述   : 单用户登录服务接口
//===================================================================

using Hbt.Common.Models;

namespace Hbt.Domain.IServices.Security
{
    /// <summary>
    /// 单用户登录服务接口
    /// </summary>
    public interface IHbtSingleUserLoginService
    {
        /// <summary>
        /// 检查用户是否可以登录
        /// </summary>
        /// <param name="userId">用户ID</param>
        /// <param name="deviceId">设备ID</param>
        /// <param name="ipAddress">IP地址</param>
        /// <param name="deviceFingerprint">设备指纹信息</param>
        /// <returns>登录检查结果</returns>
        Task<(bool canLogin, string? reason)> CheckUserLoginAsync(long userId, string deviceId, string? ipAddress = null, HbtLoginFingerprint? deviceFingerprint = null);

        /// <summary>
        /// 处理用户登录
        /// </summary>
        /// <param name="userId">用户ID</param>
        /// <param name="deviceId">设备ID</param>
        /// <param name="connectionId">连接ID</param>
        /// <param name="ipAddress">IP地址</param>
        /// <param name="userAgent">用户代理</param>
        /// <param name="userName">用户名</param>
        /// <returns>登录处理结果</returns>
        Task<HbtApiResult> HandleUserLoginAsync(long userId, string deviceId, string connectionId, string? ipAddress = null, string? userAgent = null, string? userName = null);

        /// <summary>
        /// 处理用户登出
        /// </summary>
        /// <param name="userId">用户ID</param>
        /// <param name="connectionId">连接ID</param>
        /// <param name="userName">用户名</param>
        /// <returns>是否成功</returns>
        Task<bool> HandleUserLogoutAsync(long userId, string connectionId, string? userName = null);

        /// <summary>
        /// 强制用户下线
        /// </summary>
        /// <param name="userId">用户ID</param>
        /// <param name="reason">下线原因</param>
        /// <returns>是否成功</returns>
        Task<bool> ForceUserOfflineAsync(long userId, string reason = "管理员强制下线");


        /// <summary>
        /// 检查设备是否被允许
        /// </summary>
        /// <param name="userId">用户ID</param>
        /// <param name="deviceId">设备ID</param>
        /// <returns>是否允许</returns>
        Task<bool> IsDeviceAllowedAsync(long userId, string deviceId);

        /// <summary>
        /// 验证设备指纹
        /// </summary>
        /// <param name="userId">用户ID</param>
        /// <param name="deviceId">设备ID</param>
        /// <param name="fingerprint">设备指纹</param>
        /// <returns>是否有效</returns>
        Task<bool> ValidateDeviceFingerprintAsync(long userId, string deviceId, string fingerprint);


        /// <summary>
        /// 清理过期会话
        /// </summary>
        /// <returns>清理的会话数量</returns>
        Task<int> CleanupExpiredSessionsAsync();
    }
}
